---
title: Weaviate 迁移指南：升级到客户端 v4 和服务器 1.27+
---

> 本指南说明如何从 Weaviate 客户端 v3 迁移到 v4.17.0,并将 Weaviate 服务器从 1.19.0 版本升级到 1.27.0 或更高版本。此迁移适用于包含 weaviate-client v4 升级的 Dify 版本。

## 概述

从即将发布的 Dify 版本开始,weaviate-client 已从 v3 升级到 v4.17.0。此升级带来了显著的性能改进和更好的稳定性,但需要 **Weaviate 服务器版本 1.27.0 或更高**。

<Warning>
**重大变更:**新的 weaviate-client v4 与 1.27.0 以下的 Weaviate 服务器版本不向后兼容。如果您正在运行 1.19.0 或更旧版本的自托管 Weaviate 实例,则必须在升级 Dify 之前升级您的 Weaviate 服务器。
</Warning>

### 谁会受到影响?

此迁移会影响:
- 运行低于 1.27.0 版本的自托管 Weaviate 实例的自托管 Dify 用户
- 当前使用 Weaviate 服务器 1.19.0-1.26.x 版本的用户
- 升级到包含 weaviate-client v4 的 Dify 版本的用户

**不受影响:**
- 云托管的 Weaviate 用户(Weaviate Cloud 管理服务器版本)
- 已经使用 Weaviate 1.27.0+ 的用户可以直接升级 Dify,无需额外步骤
- 运行 Dify 默认 Docker Compose 设置的用户(Weaviate 版本会自动更新)

## 重大变更

### 客户端 v4 要求

weaviate-client v4 引入了几个重大变更:

1. **最低服务器版本:**需要 Weaviate 服务器 1.27.0 或更高版本
2. **API 变更:**新的导入结构(`weaviate.classes` 而不是 `weaviate.client`)
3. **gRPC 支持:**默认使用端口 50051 上的 gRPC 以提高性能
4. **身份验证变更:**更新了身份验证方法和配置

### 为什么要升级?

- **性能:**通过 gRPC(50051)显著加快查询和导入操作
- **稳定性:**更好的连接处理和错误恢复
- **未来兼容性:**访问最新的 Weaviate 功能和持续支持
- **安全性:**Weaviate 1.19.0 已经发布一年多,不再接收安全更新

## 版本兼容性矩阵

| Dify 版本 | weaviate-client 版本 | 兼容的 Weaviate 服务器版本 |
|--------------|-------------------------|-------------------------------------|
| ≤ 1.9.1      | v3.x                    | 1.19.0 - 1.26.x                     |
| ≥ 1.9.2*     | v4.17.0                 | 1.27.0+(已测试到 1.32.11)      |

<Info>
*具体包含 weaviate-client v4 的 Dify 版本可能会有所不同。请查看您特定版本的发布说明。此迁移适用于任何使用 weaviate-client v4.17.0 或更高版本的 Dify 版本。
</Info>

<Info>
Weaviate 服务器版本 1.19.0 是一年多前发布的,现在已经过时。升级到 1.27.0+ 可以获得性能、稳定性和功能方面的众多改进。
</Info>

## 先决条件

在开始迁移之前,完成以下步骤:

1. **检查您当前的 Weaviate 版本**
   ```bash
   curl http://localhost:8080/v1/meta
   ```
   在响应中查找 `version` 字段。

2. **备份您的数据**
   - 创建 Weaviate 数据的完整备份
   - 如果使用 Docker Compose,备份您的 Docker 卷
   - 记录您当前的配置设置

3. **检查系统要求**
   - 确保有足够的磁盘空间用于数据库迁移
   - 验证 Dify 和 Weaviate 之间的网络连接
   - 如果使用外部 Weaviate,确认 gRPC 端口(50051)可访问

4. **计划停机时间**
   - 迁移需要服务停机时间
   - 如果在生产环境中运行,请通知用户
   - 在低流量时段安排迁移

## 迁移路径

选择与您的部署设置匹配的迁移路径:

### 路径 A:Docker Compose 用户(推荐)

对于通过 Docker Compose 运行 Dify 并使用捆绑的 Weaviate 实例的用户,这是最简单的路径。

<Info>
如果您使用 Dify 的标准 Docker Compose 设置,升级 Dify 时 Weaviate 版本会自动更新。无需手动配置。
</Info>

#### 步骤 1:备份您的数据

导航到您的 Dify 项目目录并备份 Docker 卷:

```bash
cd /path/to/dify/docker
docker compose down
tar -cvf ../weaviate-backup-$(date +%s).tgz volumes/weaviate
```

<Info>
将备份文件存储在项目目录之外的安全位置。如果迁移失败需要回滚,您将需要它。
</Info>

#### 步骤 2:更新 Dify

拉取包含 weaviate-client v4 和 Weaviate 1.27.0+ 的最新 Dify 版本:

```bash
cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>  # 查看发布说明以获取正确版本
cd docker
docker compose pull
docker compose up -d
```

更新的 Docker Compose 配置包括:
- Weaviate 服务器 1.27.0+ 镜像
- weaviate-client v4.17.0(在 Dify 容器中自动安装)
- 正确的 gRPC 端口配置(50051)

#### 步骤 3:监控启动

观察日志以确保服务正确启动:

```bash
# 观察 Weaviate 启动
docker compose logs -f weaviate

# 观察 Dify API 启动
docker compose logs -f api
```

等待 Weaviate 显示"ready to serve requests"和 Dify API 成功连接。

#### 步骤 4:验证迁移

请参阅下面的[验证步骤](#验证步骤)部分。

### 路径 B:外部/自托管 Weaviate

对于在独立服务器、托管实例或 Weaviate Cloud 上运行 Weaviate 的用户。

<Warning>
此路径适用于独立于 Dify 管理自己的 Weaviate 实例的用户。如果您通过 Docker Compose 使用 Dify 捆绑的 Weaviate,请改用路径 A。
</Warning>

#### 步骤 1:备份 Weaviate 数据

使用 Weaviate 的备份 API 创建完整备份:

```bash
# 创建备份
curl -X POST \
  "http://your-weaviate-host:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dify-backup-'$(date +%s)'",
    "include": ["*"]
  }'

# 检查备份状态
curl "http://your-weaviate-host:8080/v1/backups/filesystem/{backup-id}"
```

<Info>
有关详细的备份说明,请参阅 [Weaviate 备份文档](https://weaviate.io/developers/weaviate/configuration/backups)。
</Info>

#### 步骤 2:停止您的 Weaviate 实例

```bash
# 对于 Docker 用户
docker stop weaviate

# 对于 systemd 用户
sudo systemctl stop weaviate

# 对于 Kubernetes 用户
kubectl scale deployment weaviate --replicas=0
```

#### 步骤 3:升级 Weaviate 服务器

**对于 Docker:**

```bash
docker pull cr.weaviate.io/semitechnologies/weaviate:1.27.0
docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -p 50051:50051 \
  -v /path/to/data:/var/lib/weaviate \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false \
  -e AUTHENTICATION_APIKEY_ENABLED=true \
  -e AUTHENTICATION_APIKEY_ALLOWED_KEYS=your-secret-key \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  -e QUERY_DEFAULTS_LIMIT=20 \
  -e DEFAULT_VECTORIZER_MODULE=none \
  cr.weaviate.io/semitechnologies/weaviate:1.27.0
```

**对于 Kubernetes:**

更新您的 Helm values 或 manifest:

```yaml
image:
  registry: cr.weaviate.io
  repository: semitechnologies/weaviate
  tag: 1.27.0
```

然后应用:

```bash
helm upgrade weaviate weaviate/weaviate -f values.yaml
# 或
kubectl apply -f weaviate-deployment.yaml
```

**对于二进制安装:**

从 [Weaviate 发布页面](https://github.com/weaviate/weaviate/releases)下载并安装新版本。

#### 步骤 4:验证 Weaviate 升级

检查 Weaviate 是否运行正确版本:

```bash
curl http://your-weaviate-host:8080/v1/meta | jq '.version'
```

您应该看到 1.27.0 或更高版本。

#### 步骤 5:更新 Dify 配置

更新您的 Dify 环境变量以配置外部 Weaviate 连接:

```bash
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://your-weaviate-host:8080
WEAVIATE_API_KEY=your-api-key
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=your-weaviate-host:50051
```

<Info>
`WEAVIATE_GRPC_ENDPOINT` 应该采用 `hostname:port` 格式,不带任何协议前缀(没有 `grpc://` 或 `http://`)。
</Info>

#### 步骤 6:更新 Dify

```bash
cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>
cd docker
docker compose pull
docker compose up -d
```

#### 步骤 7:验证迁移

请参阅下面的[验证步骤](#验证步骤)部分。

## 旧版本的数据迁移

<Warning>
如果从 Weaviate 1.19.0 升级到 1.27.0+,版本差距很大。虽然 Weaviate 通常会自动处理模式迁移,但您应该仔细监控升级并准备好备份。
</Warning>

### 自动迁移

在大多数情况下,Weaviate 1.27.0 会自动从 1.19.0 迁移数据:

1. 停止 Weaviate 1.19.0
2. 使用相同的数据目录启动 Weaviate 1.27.0
3. Weaviate 将检测旧格式并自动迁移
4. 监控日志以获取迁移进度和任何错误

### 手动迁移(如果自动失败)

如果自动迁移失败,使用 Weaviate 的导出/导入工具:

#### 1. 从旧版本导出数据

使用游标 API 或备份功能导出所有数据。对于大型数据集,使用 Weaviate 的备份 API:

```bash
# 使用备份 API(推荐)
curl -X POST "http://localhost:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{"id": "pre-migration-backup"}'
```

#### 2. 将数据导入新版本

升级到 Weaviate 1.27.0 后,恢复备份:

```bash
curl -X POST "http://localhost:8080/v1/backups/filesystem/pre-migration-backup/restore" \
  -H "Content-Type: application/json"
```

<Info>
有关全面的迁移指导,特别是对于复杂的模式或大型数据集,请参阅官方 [Weaviate 迁移指南](https://weaviate.io/developers/weaviate/installation/migration)。
</Info>

## 配置变更

### 新环境变量

在包含 weaviate-client v4 的 Dify 版本中,提供以下新环境变量:

#### WEAVIATE_GRPC_ENDPOINT

**描述:**指定 Weaviate 连接的 gRPC 端点。使用 gRPC 可显著提高批量操作和查询的性能。

**格式:**`hostname:port`(无协议前缀)

**默认端口:**
- 不安全:50051
- 安全(TLS):443

**示例:**
```bash
# Docker Compose(内部网络)
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# 外部服务器(不安全)
WEAVIATE_GRPC_ENDPOINT=192.168.1.100:50051

# 使用自定义端口的外部服务器
WEAVIATE_GRPC_ENDPOINT=weaviate.example.com:9090

# Weaviate Cloud(443 端口上的安全/TLS)
WEAVIATE_GRPC_ENDPOINT=your-instance.weaviate.cloud:443
```

<Warning>
不要在 WEAVIATE_GRPC_ENDPOINT 值中包含协议前缀,如 `grpc://` 或 `http://`。仅使用 `hostname:port`。
</Warning>

### 更新的环境变量

所有现有的 Weaviate 环境变量保持不变:

- **WEAVIATE_ENDPOINT:**Weaviate 的 HTTP 端点(例如,`http://weaviate:8080`)
- **WEAVIATE_API_KEY:**用于身份验证的 API 密钥(如果启用)
- **WEAVIATE_BATCH_SIZE:**导入的批处理大小(默认:100)
- **WEAVIATE_GRPC_ENABLED:**启用/禁用 gRPC(v4 中默认:true)

### 完整配置示例

```bash
# docker/.env 或环境配置
VECTOR_STORE=weaviate

# HTTP 端点(必需)
WEAVIATE_ENDPOINT=http://weaviate:8080

# 身份验证(如果在您的 Weaviate 实例上启用)
WEAVIATE_API_KEY=your-secret-api-key

# gRPC 配置(推荐用于性能)
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# 批量导入设置
WEAVIATE_BATCH_SIZE=100
```

## 验证步骤

完成迁移后,验证一切是否正常工作:

### 1. 检查 Weaviate 连接

验证 Weaviate 可访问并运行正确版本:

```bash
# 检查 HTTP 端点和版本
curl http://your-weaviate-host:8080/v1/meta | jq '.version'

# 应该返回 1.27.0 或更高版本
```

### 2. 验证 Dify 连接

检查 Dify 日志以确认成功连接 Weaviate:

```bash
docker compose logs api | grep -i weaviate
```

查找指示成功连接的消息,没有"No module named 'weaviate.classes'"错误。

### 3. 测试知识库创建

1. 登录您的 Dify 实例
2. 导航到**知识库**部分
3. 创建新知识库
4. 上传测试文档(PDF、TXT 或 MD)
5. 等待索引完成
6. 检查状态是否从"QUEUING"→"INDEXING"→"AVAILABLE"变化

<Info>
如果文档停留在"QUEUING"状态,请检查 Celery worker 是否正在运行:`docker compose logs worker`
</Info>

### 4. 测试向量搜索

1. 创建或打开一个集成了知识库的聊天应用
2. 提出一个应该从您的知识库中检索信息的问题
3. 验证返回了具有正确分数的相关结果
4. 检查引用/来源链接是否正常工作

### 5. 验证 gRPC 性能

如果启用了 gRPC,您应该看到性能提升:

```bash
# 检查 gRPC 端口是否可访问
docker exec -it dify-api-1 nc -zv weaviate 50051

# 在日志中监控查询时间
docker compose logs -f api | grep -i "query_time\|duration"
```

<Info>
正确配置 gRPC 后,向量搜索查询应该比仅 HTTP 连接快 2-5 倍。
</Info>

## 故障排除

### 问题:"No module named 'weaviate.classes'"

**原因:**未安装 weaviate-client v4,或仍在使用 v3。

**解决方案:**
```bash
# 对于 Docker 安装,确保您运行的是正确的 Dify 版本
docker compose pull
docker compose down
docker compose up -d

# 对于源代码安装
pip uninstall weaviate-client
pip install weaviate-client==4.17.0
```

### 问题:gRPC 端口(50051)连接被拒绝

**原因:**端口 50051 未暴露、不可访问,或 Weaviate 未在其上监听。

**解决方案:**

1. **对于使用捆绑 Weaviate 的 Docker Compose 用户:**
   端口在容器之间内部可用。除非从 Docker 外部连接,否则无需操作。

2. **对于外部 Weaviate:**
   ```bash
   # 检查 Weaviate 是否在 50051 上监听
   docker ps | grep weaviate
   # 查找 "0.0.0.0:50051->50051/tcp"

   # 如果未暴露,请使用端口映射重启
   docker run -p 8080:8080 -p 50051:50051 ...
   ```

3. **检查防火墙规则:**
   ```bash
   # Linux
   sudo ufw allow 50051/tcp

   # 检查端口是否在监听
   netstat -tlnp | grep 50051
   ```

### 问题:身份验证错误(401 未授权)

**原因:**API 密钥不匹配或身份验证配置问题。

**解决方案:**

1. 验证 Weaviate 和 Dify 中的 API 密钥匹配:
   ```bash
   # 检查 Weaviate 身份验证
   curl http://localhost:8080/v1/meta | jq '.authentication'

   # 检查 Dify 配置
   docker compose exec api env | grep WEAVIATE_API_KEY
   ```

2. 如果使用匿名访问:
   ```yaml
   # Weaviate docker-compose.yaml
   weaviate:
     environment:
       AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
       AUTHENTICATION_APIKEY_ENABLED: 'false'
   ```

   然后从 Dify 配置中删除 `WEAVIATE_API_KEY`。

### 问题:文档停留在"QUEUING"状态

**原因:**Celery worker 未运行或未连接到 Redis。

**解决方案:**

```bash
# 检查 worker 是否正在运行
docker compose ps worker

# 检查 worker 日志
docker compose logs worker | tail -50

# 检查 Redis 连接
docker compose exec api redis-cli -h redis -p 6379 -a difyai123456 ping
# 应该返回 "PONG"

# 重启 worker
docker compose restart worker
```

### 问题:迁移后性能缓慢

**原因:**gRPC 未启用或配置不正确。

**解决方案:**

1. 验证 gRPC 配置:
   ```bash
   docker compose exec api env | grep WEAVIATE_GRPC
   ```

   应该显示:
   ```
   WEAVIATE_GRPC_ENABLED=true
   WEAVIATE_GRPC_ENDPOINT=weaviate:50051
   ```

2. 测试 gRPC 连接:
   ```bash
   docker exec -it dify-api-1 nc -zv weaviate 50051
   # 应该返回 "succeeded"
   ```

3. 如果仍然缓慢,检查 Dify 和 Weaviate 之间的网络延迟

### 问题:模式迁移错误

**原因:**Weaviate 版本之间不兼容的模式更改或数据损坏。

**解决方案:**

1. 检查 Weaviate 日志以获取特定错误消息:
   ```bash
   docker compose logs weaviate | tail -100
   ```

2. 列出当前模式:
   ```bash
   curl http://localhost:8080/v1/schema
   ```

3. 如有必要,删除损坏的集合(⚠️ 这会删除所有数据):
   ```bash
   # 先备份!
   curl -X DELETE http://localhost:8080/v1/schema/YourCollectionName
   ```

4. 重启 Dify 以重新创建模式:
   ```bash
   docker compose restart api worker
   ```

<Warning>
删除集合会移除所有数据。仅在您有备份并准备重新索引所有内容时才这样做。
</Warning>

### 问题:Docker 卷权限错误

**原因:**Docker 容器中的用户 ID 不匹配。

**解决方案:**
```bash
# 检查 Weaviate 数据目录的所有权
ls -la docker/volumes/weaviate/

# 修复权限(使用错误消息中显示的 UID)
sudo chown -R 1000:1000 docker/volumes/weaviate/

# 重启服务
docker compose restart weaviate
```

## 回滚计划

如果迁移失败需要回滚:

### 步骤 1:停止服务

```bash
cd /path/to/dify/docker
docker compose down
```

### 步骤 2:恢复备份

```bash
# 删除当前卷
rm -rf volumes/weaviate

# 从备份恢复
tar -xvf ../weaviate-backup-TIMESTAMP.tgz
```

### 步骤 3:恢复 Dify 版本

```bash
cd /path/to/dify
git checkout <previous-version-tag>
cd docker
docker compose pull
```

### 步骤 4:重启服务

```bash
docker compose up -d
```

### 步骤 5:验证回滚

检查服务是否使用旧版本运行:

```bash
# 检查版本
docker compose exec api pip show weaviate-client
curl http://localhost:8080/v1/meta | jq '.version'

# 检查错误
docker compose logs | grep -i error
```

<Info>
如果可能,请始终先在测试环境中测试回滚过程。在尝试重大迁移之前,维护多个备份副本。
</Info>

## 其他资源

### 官方文档

- [Weaviate 迁移指南](https://weaviate.io/developers/weaviate/installation/migration)
- [Weaviate v4 客户端文档](https://weaviate.io/developers/weaviate/client-libraries/python)
- [Weaviate 备份和恢复](https://weaviate.io/developers/weaviate/configuration/backups)
- [Dify 自托管指南](/zh-hans/getting-started/install-self-hosted/docker-compose)
- [Dify 环境变量](/zh-hans/getting-started/install-self-hosted/environments)

### 社区资源

- [Dify GitHub 仓库](https://github.com/langgenius/dify)
- [Dify GitHub Issues - Weaviate](https://github.com/langgenius/dify/issues?q=is%3Aissue+weaviate)
- [Weaviate 社区论坛](https://forum.weaviate.io/)
- [Dify Discord 社区](https://discord.gg/dify)

### 迁移工具

- [Weaviate Python Client v4](https://github.com/weaviate/weaviate-python-client)
- [Weaviate 备份工具](https://github.com/weaviate/weaviate/tree/main/tools)

## 总结

此迁移为 Dify 的向量存储功能带来了重要改进:

✅ **更好的性能:**gRPC 支持显著提高查询和导入速度(快 2-5 倍)

✅ **改进的稳定性:**增强的连接处理和错误恢复

✅ **安全性:**访问 Weaviate 1.19.0 中不可用的安全更新和补丁

✅ **面向未来:**访问最新的 Weaviate 功能和持续支持

虽然这是一个需要为旧版本用户升级服务器的重大变更,但好处远远超过了迁移工作。大多数 Docker Compose 用户可以通过自动更新在 15 分钟内完成迁移。

<Info>
如果您遇到本指南未涵盖的任何问题,请在 [Dify GitHub Issues 页面](https://github.com/langgenius/dify/issues)上报告,并标记"weaviate"和"migration"。
</Info>

{/*
贡献部分
不要编辑此部分!
它将由脚本自动生成。
*/}

---

[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/development/migration/weaviate-v4-migration.mdx) | [报告问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)